Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/STUTTGART/FROMUTS/REPLAY/allofit/!ARMovie/ProgIf

Text File | 1992-09-21 | 15KB | 401 lines

                      The programmer's view of Acorn Replay
                      =====================================

Introduction
------------

The software for replaying movies resides in the directory !ARMovie (think of
it like a rather large system directory - currently about 640KBytes). The !Boot
file for !ARMovie sets up the computer to play movies:

- loads the iconsprites for the AE7 filetype
- sets File$Type for AE7
- sets the RunType alias for AE7 to point to the Player program

- sets ARMovie$Dir so that the Player program knows where it is
  (there are dither tables and sound code in the directory)

- ensures the computer has ColourTrans loaded (from the system directory -
  any version will do)

After this, double clicking on an Acorn Replay Movie will play the movie on the
desktop. Just running the program at the cli will play it. A program can do:

SYS"Wimp_StartTask","movie file name"

to play the movie.

The program attached to !ARMovie is a minimal desktop viewer for replay files -
it can display the helpful sprite and allows desktop control of a few of the
capabilities of the Acorn Replay Player program. See the section on ARMovie$Dir
below for information on how to treat !ARMovie.

Note that the Player program has to take over the entire machine in order to
get its work done. It consists of independant interrupt run processes:

- file chunk loader
- master time 'conductor'
- video decompressor
- video frame refresh and dither
- sound player
- mouse event handler

The video sections of this code are custom assembled to suit the particular
screen mode etc.

The interrupt run processes are communicating using shared memory in the
ordinary virtual address space - a wimp task swap would be fatal... A large
amount is memory is required:

- double buffer for the file I/O (odd and even chunk size given in the
  AE7 file header)
- double buffered queue of decompressed frames
- queue of sound chunks

The amount of memory required is at least:

  "odd" chunk size + "even" chunk size + 320K
  + 48K (or more) if sound is to be played
  + 128K for dithering tables
  (the video compressor program gives an accurate value)

The Player program can use more memory if it is available! It will (by default)
return with a textual error if there isn't enough memory.

A major limitation of the video frame refresh and dither section of the
program is that it uses word addressing in order to paint on the screen:
this results in the displayed section be somewhat to the left or right of
the desired position. With 16bpp it can be 2 pixels out, 8 bpp 4 pixels, 4bpp
8 pixels, 2bpp 16 pixels, 1bpp 8 pixels. The program rounds the pixel address
to the word address to minimise the total effect, thus making it 16bpp +/- 1
pixel etc.

ADPCM sound is Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam,
The Netherlands. See notice at the end.

Simple Control
--------------

The Player program has some default controls in it:

Esc

   The Esc key terminates a display sequence.

Menu (Mouse middle button)

   The Menu button (also) terminates a display sequence.

Adjust (Mouse right button)

   The Adjust button pauses video and sound while it is held down.

Other capabilities may be provided as icons by the calling program.

Parameters
----------

The Player program also accepts a list of parameters on the command line after
the Acorn Replay movie file. These are

-At <Number>,<Number>

   Specifies the position of the bottom left corner of the replayed movie in
   OS units x,y. Player will move the output display such that it is entirely
   on screen. Note the comments above about precision of positionning the
   output.

-Big

   If the movie is <=160 X, <=128 Y, then Player will play it on a Mode 13
   320 by 256 pixel screen filling the screen. If the movie is <=192 X,
   <=144 Y, then Player will install a temporary Mode 96 which gives an
   overscanned Mode 13 display and play the movie filling the screen.

   The -nomenu flag is overridden when -big is asserted.

-Explode <Dir$>

   Player decompresses the specified section of the movie (-startat and
   -playfor) and places the result as a sequence of frames in the directory
   Dir$ with the following name for each frame:

      FNZNUM(frame%DIV75DIV77)+"."+FNZNUM(frame%DIV75 MOD77)+"."+FNZNUM(frame%MOD75)
      DEF FNZNUM(A)=RIGHT$("0"+STR$(A),2)

   Frames start at zero. Each frame is stored as a p15 file (textual header
   plus 5,5,5 R,G,B data held as uncompressed 16 bit values with R as bits
   0-4, G as bits 5-9, B as bits 10-14). This can take quite a while!

-Leave

   By default, Player removes the output from the display. If -Leave is
   specified it will leave the output on the display when the program is
   left (either by getting to the end or Escape/Menu). Leave state is forced
   if the user exits by clicking on the CAPTURE/EXIT button.

-Loop

   Player will loop back to the start of the movie when it gets to the end,
   thus playing for ever. This overrides -playfor.

-Loop <number>

   Player will loop back to the start of the movie when it gets to the end,
   for the specified number of times.

   Note that both forms of loop may have problems on a CD-ROM where access
   time to move the head from finish to start might cause a break in the
   sequence.

-Mute

   Player starts up with sound initially turned off.

-NoAdjust

   Suppresses the use of Adjust for pause.

-NoError

   Suppresses all possible textual errors from the Player program. The
   variable ARMovie$ReturnCode will contain the error.

-NoMenu

   Suppresses the use of Menu for exit.

-PlayFor <Number>

   <Number> represents a time in centiseconds: this amount of the movie is
   played and the program exits. Note that Pause, fast forward, half speed
   etc. do not affect this time limit - it represents a duration in frames
   (or feet of the original film) rather than a time in the future.

-Quiet

   Disables the sound permanently. (Unlike -Mute it cannot be turned back on
   with the controls if they are provided)

-Relative

   Changes button definitions such that the origin is relative to the -at
   value rather than absolute.

-Startat <Number>

   <Number> represents a time in centiseconds: the movie is played from this
   point. It can be very time consuming to reach a random point in a none
   key frame movie, but Player can do it if necessary. Key frame movies
   should only take a few seconds to start playing at any point.

-Silent

   Starts playing with sound initially disabled.

-Speed <Number>

   <Number> represents a speed up ratio: the movie is played faster or
   slower than normal. For example -speed 2 or -speed 0.5 for twice speed
   or half speed play. It is recommended that -mute is used at the same time
   as -speed... No attempt is made to enforce speed ratios that the computer
   can actually decompress, so use with care!

-Track <Number>

   <Number> selects which of the multiple sound tracks in the ARMovie file is
   played. The track must exist.

In addition to those parameters, the calling program can specify the positions
of control buttons on screen. The Player program caters for buttons with the
following functions:

   exit
   capture exit (exactly like exit, but leaves pixel map on screen)
   pause
   single frame advance when in pause mode
   fast forward
   half speed
   quiet (no sound)
   loud (sound back on)
   mute (toggle sound)

By default no button definitions exist except for pause, defined as the
whole screen: so by default a left click will pause the movie and another
will restart it. Buttons are defined with the initial character followed by
the bottom left corner i.e. E10,40 - this gives a default sized button of 32
OS units. E10,40,50 gives a square button of 50 OS units. E10,40,50,25 gives
a rectangular button 50 OS units wide, 25 tall. (-relative makes button
definitions relative to the -at position). Defining any button position will
remove the effect of the default pause button; use -NoMenu and -NoAdjust if
you need to prevent the other mouse buttons.

A typical command line might be:

<movie name> -loop -leave -startat 2000 -playfor 2000 -quiet E640,512 P0,0

case is irrelevant.

System Variables
----------------

There are several system variables which affect the Acorn Replay player program:

ARMovie$Dir

   This is set by the !ARMovie application so that Player can get at its
   resources - Player won't work without this variable! Applications should
   only set this variable if it is not already set: for example, suppose you
   wish to play a movie on filer_boot of your application and therefore need
   to have Player work and have therefore included a copy of !ARMovie on your
   disc. You should do:

   IF "<ARMovie$Dir>"="" THEN Run <My$Dir>.!ARMovie.!Boot

   This allows for new versions of the !ARMovie application to replace the one
   on your disc by being seen first. IT WILL BE NECESSARY FOR THIS TO HAPPEN:
   FOR EXAMPLE, NEW VIDEO HARDWARE WILL NEED NEW VERSIONS OF !ARMovie AND
   Player.

ARMovie$Place

   Contains the position on screen where the player will put the movie as
   <leftx> <bottomy> - for example *set ARMovie$Place 640 512

   Controlling programs must set this immediately before running the movie.

   Value is only used if -At parameter is not given.

ARMovie$PrefMode

   Used by the machine's owner to get the movie to display in a different
   mode to the current one. For example, a user may like working in a very
   high resolution mode with a low number of colours. Player can display
   movies in such modes but they don't look good, so the user can set
   ARMovie$PrefMode to an alternative mode. Note that the user won't be able
   to see the buttons. (Currently ARMovie$PrefMode is the only way to get
   playback in 16 bit per pixel modes, since the desktop doesn't operate
   in those modes).

   If ARMovie$PrefMode is 13, then -Big is assumed.

[Aside: minimal mode if -1: Player installs a 320x128 pixel temporary Mode 96
with the same timing as Mode 15.]

ARMovie$Suffix

   Used by the machine's owner to preselect different versions of the
   movie if they are available. For example, if one knows that one's machine
   can only manage 12.5fps movies, *set ARMovie$Suffix to 2 and Player will
   preferentially play the 12.5fps movies. See the file on AE7 file naming
   conventions.

ARMovie$4Colour

   If this variable is defined, then square pixel hi-resolution (e.g. mode 27)
   displays will be done in colour, provided a lookup table has been defined.
   The quality of this is not wonderful, particularly in the red/magenta area
   of the colour space, because these colours are missing from the default
   RISC OS colour palette.

   The program 'Make4col11", in the !ARMovie.MovingLine directory, will make
   the appropriate lookup tables for the current palette: this does take
   some time... The !ARMovie directory needs to be on a writeable file
   system in order for the extra files to be written to it.

Some system variables are used by Player to return information to the calling
programs:

ARMovie$Return

   Player sets this to the actual position on screen of the video information.
   If -leave has been set or use user has exitted Player using the CAPTURE/EXIT
   button, this is the section that has been 'dirtied' and should be repainted
   by the window manager. It is set to

   <leftx> <bottomy> <rightx> <topy> <C>

   where the <C> is present only if the user has pressed CAPTURE/EXIT.

ARMovie$ReturnCode

   If -NoError has been set, this will contain the textual error message.
   It will not exist if there was no error.

ARMovie$Sound

   Player sets this to 0 if the sound has been disabled by clicking on
   one of the icons, 1 if it is enabled. This, plus the use of -mute,
   allows sound on/off state to be preserved between the applications and
   the Player program.

ARMovie$Time

   Player sets this to the number of centiseconds of movie which have been
   played. Note that (like -playfor) this refers strictly to the amount of
   the movie, not the total elapsed time: playing a movie and playing the
   movie pausing every frame for an hour will end up with the same value
   for ARMovie$Time.

ARMovie$Version

   Player sets this to its version number and date string.

Acorn Replay Icons
------------------

The !ARMovie application has already *iconsprite'd the icons for the AE7
filetype into the window manager's icon pool - you should not include them
(or any other system icons...) in your application's own !Sprite files.

A standard set of icons is made available for the buttons used to control
the player. They are in <ARMovie$Dir>.Sprites (plus Sprites22 and Sprites23
using the RISC OS 3.00 discipline for alternative resolutions). This gives
all eight buttons with names 'exit' 'pause' 'single' 'fast' 'half' 'quiet'
'loud' and 'mute'. In addition, there are 'play' and 'pplay' (pushed play)
buttons to complete a control panel.

Applications wishing to use the button set should load (check for failure)
the sprite file into their own sprite area (rather than *iconsprite'ing
it - the definitions use up quite a bit of memory).

If you wish to use your own icons for control buttons (for example, you
want the buttons to be a different size) then please ensure that the
buttons appearance (especially the shape of the glyph design) is close to
the standard ones.

The sprite file <ARMovie$Dir>.Default contains the default sprite used by
the !ARMovie program to indicate that an ARMovie file can be dragged there.

Not done yet
------------

The player does not, in fact, respond to double speed and half speed play.

ADPCM sound copyright notice
----------------------------

ADPCM sound code was implemented by Mark Taunton of Acorn Computers using
original code supplied with the following notice:

Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam, The
Netherlands.

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the names of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.